---
title: "Module Configuration"
description: "Learn how to configure Dagger modules, including TypeScript SDK settings, file filters, and alternative runtimes."
keywords: ["dagger", "module", "configuration", "typescript", "sdk", "runtime", "package manager"]
sidebar_label: "Modules"
slug: /reference/configuration/modules
---


Modules can be configured by editing their `dagger.json` file. The configuration in there contains all module metadata - from the name of the module and the SDK it uses, to the dependencies it requires. An initial configuration is automatically generated when using `dagger init` or `dagger develop` for the first time, and is kept up-to-date with `dagger config`/`dagger install`/etc.

For more information, refer to the [JSON schema for the Dagger module configuration file](https://docs.dagger.io/reference/dagger.schema.json).

## File and directory filters

The JSON schema for the Dagger module configuration file `dagger.json` supports an `include` field. It tells the Dagger Engine of additional files to include or exclude when loading the module itself. By default, only `dagger.json` and all files under the module's source directory are included.

Notably, these filters only apply to loading the Dagger module. They do not apply to any directories passed as arguments to the Dagger module's functions ([pre- and post-call filtering](../../getting-started/types/directory.mdx#filters) is separately available for directory arguments).

:::tip
Adding excluding patterns prefixed with `!` is particularly useful during local module development, to avoid uploading large cache or generated files that the Dagger Engine doesn't need.
:::

## TypeScript

TypeScript-specific SDK settings can be configured using the standard
`package.json` file.

### Alternative runtimes

TypeScript is supported by multiple runtimes: [Node.js](https://nodejs.org/en) (via `tsx`), [Deno](https://deno.com/) (natively) and [Bun](https://bun.sh/) (natively). The Dagger TypeScript SDK supports all of these, although Bun and Deno support is currently experimental.

By default, the TypeScript SDK executes functions using the Node.js runtime, but you can configure an alternative runtime in your Dagger module's `package.json` file.

To change the TypeScript SDK runtime, refer to the sections below.

<Tabs groupId="ts_runtime" queryString="ts_runtime">
<TabItem value="nodejs" label="Node.js">
Set the field to `node` to use the Node.js runtime. Node.js is also the default runtime used if this field is omitted.

```json
  "dagger": {
    "runtime": "node"
  }
```

You can also set a specific version with a suffix (e.g., `node@20.15.0`).

```json
  "dagger": {
    "runtime": "node@20.15.0"
  }
```
</TabItem>
<TabItem value="bun" label="Bun">

:::warning
Bun runtime support is still experimental. Unexpected results may occur in some cases.
:::

Set the field to `bun` to use the Bun runtime (and its package manager).

```json
  "dagger": {
    "runtime": "bun"
  }
```

You can also set a specific version with a suffix (e.g., `bun@1.0.11`).

```json
  "dagger": {
    "runtime": "bun@1.0.11"
  }
```

If `dagger.runtime` is not set, but a `bun.lock` or `bun.lockb` file is present, Dagger will [automatically detect](#automatic-detection) and configure Bun for use. You can generate this file with `bun init` and `bun install`, as in the example below:

```shell
bun init
bun install // to generate the bun.lock file
dagger init --sdk=typescript --name=example --source=.
```

:::important
The module's `source` field must reference the same directory as the `bun.lock` or `bun.lockb` file.
:::
</TabItem>
<TabItem value="deno" label="Deno">

:::warning
Deno runtime support is still experimental. Unexpected results may occur in some cases.
:::

If a `deno.json` file is present, Dagger will [automatically detect](#automatic-detection) and configure Deno for use. You can generate this file with `deno init`, as in the example below:

```shell
deno init
dagger init --sdk=typescript --name=example --source=.
```

:::important
The module's `source` field must reference the same directory as the `deno.json` file.
:::
</TabItem>
</Tabs>

#### Automatic detection

When a runtime is not explicitly defined within the `package.json` file, Dagger automatically identifies the appropriate runtime by examining the project's files inside the project's `dagger` directory.

- If Dagger finds any of the following lock files : `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`, it automatically selects `node` as the runtime.
- In the absence of the lock files mentioned above, if a `bun.lock` or `bun.lockb` file is present, Dagger will choose `bun` as the runtime. Alternatively, if a `deno.json`, or `deno.lock`, file is present, Dagger will choose `deno` as the runtime.
- If no or only unknown lock files are present, `node` is chosen.

:::warning
This behavior however should be seen as a sensible fallback and not as an explicit configuration.
:::

### Alternative package managers

TypeScript can manage dependencies using multiple package managers. The [Node.js](https://nodejs.org/en) runtime supports [`npm`](https://www.npmjs.com/), [`pnpm`](https://pnpm.io/) and [`yarn`](https://yarnpkg.com/). The [Bun](https://bun.sh/) runtime supports `bun`.

By default, the TypeScript SDK executes functions using the Node.js runtime with [yarn v1.22.22](https://yarnpkg.com/), but you can configure an alternative package manager or version in your Dagger module's `package.json` file by setting the `packageManager` property.

#### Npm

Set the `packageManager` property to `npm` to use the `npm` package manager. You can also set a specific version with a suffix, as shown below:

```json
  "packageManager": "npm@10.8.2"
```

If no version is specified, `npm@10.7.0` is used by default.

#### Yarn

Set the `packageManager` property to `yarn` to use the Yarn package manager. You can also set a specific version with a suffix, as shown below:

```json
  "packageManager": "yarn@1.22.21"
```

If no version is specified, `yarn@1.22.22` is used by default.

If you use Yarn 3.0 or above, the TypeScript SDK will also generate a `.yarnrc.yml` file in your module's root directory. This file is used to configure the Yarn package manager linker to `node_modules`, which is  required to correctly resolve `@dagger.io/dagger` as local dependencies of your module.

```yaml
nodeLinker: node-modules
```

#### Pnpm

Set the `packageManager` property to `pnpm` to use the Pnpm package manager. You can also set a specific version with a suffix, e.g.:

```json
  "packageManager": "pnpm@9.9"
```

If no version is specified, `pnpm@8.15.4` is used.

The TypeScript SDK will also generate a `pnpm-workspace.yml` file in your module's root directory. This file is used to configure the Pnpm package manager, which is required to correctly resolve `@dagger.io/dagger` as local dependencies of your module.

```yaml
packages:
  - './sdk'
```

#### Automatic detection

When a package manager is not explicitly defined within the `package.json` file, Dagger automatically identifies the appropriate package manager by examining the project's lock files inside the project's `.dagger` directory.

- If Dagger finds any of the following lock files : `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`, it automatically selects the corresponding package manager with a predefined default version: `npm@10.7.0`, `yarn@1.22.22` or `pnpm@8.15.4`.
- If none of the above mentioned lock files are present, but a `bun.lock` or `bun.lockb` file is present, Dagger will choose `bun` as the runtime and package manager with a predefined default version: `bun@1.0.11`.
- `yarn@1.22.22` is the last default, when nothing mentioned above applies.

:::warning
This behavior however should be considered a sensible fallback, and not as an explicit configuration. Since this default can change, we encourage you to configure a package manager explicitly.
:::

### Alternative base images

The image to use is derived from the version in the `dagger.runtime` field if it's present. If this is not suitable for your needs, you can specify a custom base image in your module's `package.json`, tailoring the SDK to your project's needs.

:::warning
It is recommended to use this feature only for advanced use cases such as adding bespoke environment variables, authentication files or operating system packages to the runtime container. Ensure that you avoid deviating from the default image too much, as doing so could create unexpected results.
:::

To change the base image, set the field `dagger.baseImage` in your Dagger module's `package.json` file.

```json
{
  "dagger": {
    "baseImage": "node:23.2.0-alpine@sha256:ecefaffd4706c5879af52e022fdb8ea30cbd6590e2a30d05347790d690727c6c"
  }
}
```

:::note
Currently, only Alpine-based images are supported.
:::

### Bundled or vendored SDK

By default, the SDK is installed as a bundled local dependency, so all SDK related dependencies are already pre-bundled in the module's code
and no extra dependencies are added to the module's `package.json` file.

The `tsconfig.json` is configured to import the bundled SDK from the `sdk` directory and correctly map imports paths:

```json
{
    "paths": {
      "@dagger.io/dagger": ["./sdk/index.ts"],
      "@dagger.io/dagger/telemetry": ["./sdk/telemetry.ts"]
    }
}
```

The bundled SDK ensures better performance and compatibility with all the runtimes, without conflicting with the module's own dependencies.

However, you can also configure the SDK as a local vendored dependency:

```shell
# Cleanup the current SDK module's directory
rm -rf ./sdk

# Add `@dagger.io/dagger` as a local dependency
npm pkg set "dependencies[@dagger.io/dagger]=./sdk"

# Re generate the module's directory
dagger develop
```

This will generate a new `sdk` directory with the SDK as a vendored library and will update the `tsconfig.json` with the new import paths.

```json
{
    "paths": {
      "@dagger.io/dagger": ["./sdk/src"],
      "@dagger.io/dagger/telemetry": ["./sdk/src/telemetry"]
    }
}
```

This may be useful if you share common dependencies between your module and the Dagger Engine but it will impact
performance.

To migrate from the local vendored SDK dependency back to the bundled SDK, reverse the process:

```shell
# Cleanup the current SDK module's directory
rm -rf ./sdk

# Remove `@dagger.io/dagger` from dependencies
npm pkg delete "dependencies[@dagger.io/dagger]"

# Re generate the module's directory
dagger develop
```
